<?php

// ------------------------------------------------------------------------
// |@Author       : Jarmin <topextend@qq.com>
// |@----------------------------------------------------------------------
// |@Date         : 2025-05-04 23:29:01
// |@----------------------------------------------------------------------
// |@LastEditTime : 2025-05-08 22:59:50
// |@----------------------------------------------------------------------
// |@LastEditors  : Jarmin <topextend@qq.com>
// |@----------------------------------------------------------------------
// |@Description  : 响应处理特征
// |@----------------------------------------------------------------------
// |@FilePath     : ResponseTrait.php
// |@----------------------------------------------------------------------
// |@Copyright (c) 2025 http://www.ladmin.cn All Rights Reserved.
// ------------------------------------------------------------------------
declare (strict_types=1);

namespace think\admin\traits;

use think\Response;

/**
 * 响应处理特征
 *
 * 核心功能：
 * 1. 提供统一的响应方法
 * 2. 支持业务状态码和HTTP状态码
 * 3. 支持成功和错误响应
 * 4. 支持分页数据响应
 *
 * @package think\admin\traits
 * @version 1.0.0
 */
trait ResponseTrait
{
    use ErrorCodeTrait;
    use HttpStatusTrait;

    /**
     * 统一响应方法
     *
     * @param mixed $data 响应数据
     * @param string $message 提示信息
     * @param int $code 业务状态码
     * @param int $httpCode HTTP状态码
     * @return Response
     */
    protected function response(mixed $data = null, string $message = '', int $code = 0, int $httpCode = 200): Response
    {
        return json([
            'code' => $code,
            'message' => $message ?: $this->getErrorMessage($code),
            'data' => $data,
            'timestamp' => time()
        ])->code($httpCode);
    }

    /**
     * 成功响应
     *
     * @param mixed $data 响应数据
     * @param string $message 提示信息
     * @param int $code 业务状态码
     * @return Response
     */
    protected function success(mixed $data = null, string $message = '', int $code = self::SUCCESS): Response
    {
        return $this->response($data, $message, $code, self::HTTP_OK);
    }

    /**
     * 错误响应
     *
     * @param string $message 错误信息
     * @param int $code 业务错误码
     * @param mixed $data 错误数据
     * @return Response
     */
    protected function error(string $message = '', int $code = self::ERROR, mixed $data = null): Response
    {
        // 根据业务错误码获取对应的HTTP状态码
        $httpCode = $this->getHttpStatusCode($code);
        return $this->response($data, $message ?: $this->getErrorMessage($code), $code, $httpCode);
    }

    /**
     * 分页数据响应
     *
     * @param array $list 数据列表
     * @param int $total 总记录数
     * @param int $page 当前页码
     * @param int $limit 每页数量
     * @return Response
     */
    protected function paginate(array $list, int $total, int $page = 1, int $limit = 20): Response
    {
        return $this->success([
            'list' => $list,
            'total' => $total,
            'page' => $page,
            'limit' => $limit,
            'pages' => (int)ceil($total / $limit)
        ]);
    }

    /**
     * 创建成功响应
     * @param mixed $data 响应数据
     * @param string $message 提示信息
     * @return Response
     */
    protected function created(mixed $data = null, string $message = ''): Response
    {
        return $this->response($data, $message, self::SUCCESS, self::HTTP_CREATED);
    }

    /**
     * 更新成功响应
     * @param mixed $data 响应数据
     * @param string $message 提示信息
     * @return Response
     */
    protected function updated(mixed $data = null, string $message = ''): Response
    {
        return $this->success($data, $message ?: '更新成功');
    }

    /**
     * 删除成功响应
     * @param string $message 提示信息
     * @return Response
     */
    protected function deleted(string $message = ''): Response
    {
        return $this->response(null, $message ?: '删除成功', self::SUCCESS, self::HTTP_NO_CONTENT);
    }

    /**
     * 未授权响应
     * @param string $message 错误信息
     * @param mixed $data 错误数据
     * @return Response
     */
    protected function unauthorized(string $message = '', mixed $data = null): Response
    {
        return $this->error($message, self::AUTH_ERROR, $data);
    }

    /**
     * 禁止访问响应
     * @param string $message 错误信息
     * @param mixed $data 错误数据
     * @return Response
     */
    protected function forbidden(string $message = '', mixed $data = null): Response
    {
        return $this->error($message, self::REQUEST_FORBIDDEN, $data);
    }

    /**
     * 资源不存在响应
     * @param string $message 错误信息
     * @param mixed $data 错误数据
     * @return Response
     */
    protected function notFound(string $message = '', mixed $data = null): Response
    {
        return $this->error($message, self::DATA_NOT_FOUND, $data);
    }

    /**
     * 验证错误响应
     * @param string $message 错误信息
     * @param mixed $data 错误数据
     * @return Response
     */
    protected function validateError(string $message = '', mixed $data = null): Response
    {
        return $this->error($message, self::VALIDATE_ERROR, $data);
    }
}
